Libris Britannia 4/science library(b).zip/science library(b)/DJGPP/DJ111M2.ZIP/docs/djgpp/libc-d-f.tex

Text File | 1994-01-08 | 40KB | 1,827 lines

@c ----------------------------------------------------------------------
@node delay, difftime, _ctype_, Alphabetical List

@heading @code{delay}
@subheading Syntax

@example
void delay(unsigned msec);
@end example

@subheading Description

This function causes the program to pause for @var{msec} milliseconds.
It uses the @code{int 15h} delay function to relinquish the CPU to other
programs that might need it.

@subheading Return Value

None.

@subheading Example

@example
delay(200); /* delay for 1/5 second */
@end example

@c ----------------------------------------------------------------------
@node difftime, disable, delay, Alphabetical List

@heading @code{difftime}
@subheading Syntax

@example
#include <time.h>

double difftime(time_t t1, time_t t0);
@end example

@subheading Description

This function returns the difference in time, in seconds, from @var{t0}
to @var{t1}.

@subheading Return Value

The number of seconds.

@subheading Example

@example
time_t t1, t0;
double elapsed;
time(&t0);
do_something();
time(&t1);
elapsed = difftime(t1, t0);
@end example

@c ----------------------------------------------------------------------
@node disable, div, difftime, Alphabetical List

@heading @code{disable}
@subheading Syntax

@example
#include <dos.h>

void disable(void);
@end example

@subheading Description

This function disables interrupts.

@xref{enable}

@subheading Return Value

None.

@subheading Example

@example
disable();
...
enable();
@end example

@c ----------------------------------------------------------------------
@node div, _doprnt, disable, Alphabetical List

@heading @code{div}
@subheading Syntax

@example
#include <stdlib.h>

div_t div(int numberator, int denomonator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numberator}
divided by @var{denomonator}.  The return type is as follows:

@example
typedef struct @{
  int quot;
  int rem;
@} div_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Example

@example
div_t d = div(42, 3);
printf("42 = %d x 3 + %d\n", d.quot, d.rem);
@end example

@c ----------------------------------------------------------------------
@node _doprnt, _doscan, div, Alphabetical List

@heading @code{_doprnt}
@subheading Syntax

@example
#include <stdio.h>

int _doprnt(const char *format, void *params, FILE *file);
@end example

@subheading Description

This is an internal function that is used by all the @code{printf} style
functions, which simply pass their format, arguments, and stream to this
function.

@xref{printf} for a discussion of the allowed formats and arguments.

@subheading Return Value

The number of characters generated is returned.

@subheading Example

@example
int args[] = @{ 1, 2, 3, 66 @};
_doprnt("%d %d %d %c\n", args, stdout);
@end example

@c ----------------------------------------------------------------------
@node _doscan, _doscan_low, _doprnt, Alphabetical List

@heading @code{_doscan}
@subheading Syntax

@example
#include <stdio.h>

int _doscan(FILE *file, const char *format, void **ptrs_to_args);
@end example

@subheading Description

This is an internal function that is used by all the @code{scanf} style
functions, which simply pass their format, arguments, and stream to this
function.

@xref{scanf} for a discussion of the allowed formats and arguments.

@subheading Return Value

The number of characters successfully scanned is returned, or -1 on
error.

@subheading Example

@example
int x, y;
int *args[2];
args[0] = &x;
args[1] = &y;
_doscan(stdin, "%d %d", args);
@end example

@c ----------------------------------------------------------------------
@node _doscan_low, dosmemget, _doscan, Alphabetical List

@heading @code{_doscan_low}

@subheading Description

This is an internal function used by _doscan.

@c ----------------------------------------------------------------------
@node dosmemget, dosmemput, _doscan_low, Alphabetical List

@heading @code{dosmemget}
@subheading Syntax

@example
#include <go32.h>

void dosmemget(int offset, int length, void *buffer);
@end example

@subheading Description

This function transfers data from MS-DOS's conventional memory space to
the program's virtual address space.  The @var{offset} is a physical
address, which can be computed from a real-mode segment/offset pair as
follows:

@example
offset = segment * 16 + offset;
@end example

The @var{length} is the number of bytes to transfer, and @var{buffer} is
a pointer to somewhere in your virtual address space (such as memory
obtained from @code{malloc}) where the data will go.

@subheading Return Value

None.

@subheading Example

@example
unsigned short shift_state;
dosmemget(0x417, 2, &shift_state);
if (shift_state & 0x0004)
  /* Ctrl key pressed */;
@end example

@c ----------------------------------------------------------------------
@node dosmemput, dup, dosmemget, Alphabetical List

@heading @code{dosmemput}
@subheading Syntax

@example
#include <go32.h>

void dosmemput(const void *buffer, int length, int offset);
@end example

@subheading Description

This function transfers data from the program's virtual address space to
MS-DOS's conventional memory space.  The @var{offset} is a physical
address, which can be computed from a real-mode segment/offset pair as
follows:

@example
offset = segment * 16 + offset;
@end example

The @var{length} is the number of bytes to transfer, and @var{buffer} is
a pointer to somewhere in your virtual address space (such as memory
obtained from @code{malloc}) where the data will come from.

@subheading Return Value

None.

@subheading Example

@example
unsigned short save_screen[25][80];
dosmemput(save_screen, 0xb8000, 80*2*25);
@end example

@c ----------------------------------------------------------------------
@node dup, dup2, dosmemput, Alphabetical List

@heading @code{dup}
@subheading Syntax

@example
#include <osfcn.h>

int dup(int old_handle);
@end example

@subheading Description

This function duplicates the given file handle.  Both handles refer to
the same file and file pointer.

@subheading Return Value

The new file handle, or -1 if error.

@subheading Example

@example
do_file(dup(fileno(stdin)));
@end example

@c ----------------------------------------------------------------------
@node dup2, enable, dup, Alphabetical List

@heading @code{dup2}
@subheading Syntax

@example
#include <osfcn.h>

int dup2(int existing_handle, int new_handle);
@end example

@subheading Description

This call causes @var{new_handle} to refer to the same file and file
pointer as @var{existing_handle}.  If @var{new_handle} is an open file,
it is closed.

@subheading Return Value

The new handle, or -1 on error.

@subheading Example

@example
/* copy new file to stdin stream */
close(0);
dup2(new_stdin, 0);
close(new_stdin);
@end example

@c ----------------------------------------------------------------------
@node enable, endgrent, dup2, Alphabetical List

@heading @code{enable}
@subheading Syntax

@example
#include <dos.h>

void enable(void);
@end example

@subheading Description

This function enables interrupts.

@xref{disable}

@subheading Return Value

None.

@subheading Example

@example
disable();
...
enable();
@end example

@c ----------------------------------------------------------------------
@node endgrent, endmntent, enable, Alphabetical List

@heading @code{endgrent}
@subheading Syntax

@example
#include <grp.h>

void endgrent(void);
@end example

@subheading Description

This function should be called after all calls to getgrent, getgrgid, or
getgrnam.

@subheading Return Value

None.

@subheading Example

@xref{getgrent}

@c ----------------------------------------------------------------------
@node endmntent, endpwent, endgrent, Alphabetical List

@heading @code{endmntent}
@subheading Syntax

@example
#include <mntent.h>

int endmntent(FILE *filep);
@end example

@subheading Description

This function should be called after the last call to getmntent (@xref{getmntent}).

@subheading Return Value

This function always returns one.

@c ----------------------------------------------------------------------
@node endpwent, errno, endmntent, Alphabetical List

@heading @code{endpwent}
@subheading Syntax

@example
#include <pwd.h>

void endpwent(void);
@end example

@subheading Description

This function should be called after the last call to getpwent (@xref{getpwent}).

@subheading Return Value

None.

@c ----------------------------------------------------------------------
@node errno, exec*, endpwent, Alphabetical List

@heading @code{errno}
@subheading Syntax

@example
#include <errno.h>

extern int errno;
@end example

@subheading Description

This variable is used to hold the value of the error of the last
function call.  For details about the various error types, please refer
to the file @file{include/errno.h}.

@xref{perror}

@c ----------------------------------------------------------------------
@node exec*, _exit, errno, Alphabetical List

@heading @code{exec*}
@subheading Syntax

@example
#include <process.h>

int execl(const char *path, const char *argv0, ...);
int execle(const char *path, const char *argv0, ... /*, const char **envp */);
int execlp(const char *path, const char *argv0, ...);
int execlpe(const char *path, const char *argv0, ... /*, const char **envp */);

int execv(const char *path, const char **argv);
int execve(const char *path, const char **argv, const char **envp);
int execvp(const char *path, const char **argv);
int execvpe(const char *path, const char **argv, const char **envp);
@end example

@subheading Description

These functions operate by calling @code{spawn*} with a type of
@code{P_OVERLAY}.  Refer to @xref{spawn*} for a full description.

@subheading Return Value

If successful, these functions do not return.  If there is an error,
these functions return -1 and set @code{errno} to indicate the error.

@subheading Example

@example
execlp("gcc", "gcc", "-v", "hello.c", 0);
@end example

@c ----------------------------------------------------------------------
@node _exit, exit, exec*, Alphabetical List

@heading @code{_exit}
@subheading Syntax

@example
#include <stdlib.h>

void volatile _exit(int exit_code);
@end example

@subheading Description

This function exits the application immediately, without performing any
@code{atexit} or @code{on_exit} requests or closing any files.  The
program will return @var{exit_code} to the calling process as the exit
code.

@subheading Return Value

This function does not return.

@c ----------------------------------------------------------------------
@node exit, _f_morefiles, _exit, Alphabetical List

@heading @code{exit}
@subheading Syntax

@example
#include <stdlib.h>

void volatile exit(int exit_code);
@end example

@subheading Description

This function exits the program, returning @var{exit_code} to the
calling process.  Before exiting, all open files are closed and all
@code{atexit} and @code{on_exit} requests are processed.

@subheading Return Value

This function does not return.

@subheading Example

@example
if (argc < 4)
@{
  print_usage();
  exit(1);
@}
@end example

@c ----------------------------------------------------------------------
@node _f_morefiles, fchmod, exit, Alphabetical List

@heading @code{_f_morefiles}

@subheading Description

This is an internal function used by @code{fopen}. @xref{fopen}

@c ----------------------------------------------------------------------
@node fchmod, fclose, _f_morefiles, Alphabetical List

@heading @code{fchmod}
@subheading Syntax

@example
#include <unistd.h>

int fchmod(int file, int mode);
@end example

@subheading Description

This function is not implemented under MS-DOS.  If you call it, it will
only write a warning to stderr.

@c ----------------------------------------------------------------------
@node fclose, fdopen, fchmod, Alphabetical List

@heading @code{fclose}
@subheading Syntax

@example
#include <stdio.h>

int fclose(FILE *file);
@end example

@subheading Description

This function closes the given @var{file}.

@subheading Return Value

Zero on success, else @code{EOF}.

@subheading Example

@example
FILE *f = fopen("data", "r");
fprintf(f, "Hello\n");
fclose(f);
@end example

@c ----------------------------------------------------------------------
@node fdopen, feof, fclose, Alphabetical List

@heading @code{fdopen}
@subheading Syntax

@example
#include <stdio.h>

FILE *fdopen(int fd, const char *mode);
@end example

@subheading Description

This function opens a stream-type file that uses the given @var{fd}
file, which must already be open.  The file is opened with the modes
specified by @var{mode}, which is the same as for @code{fopen}.
@xref{fopen}

@subheading Return Value

The newly created @code{FILE *}, or @code{NULL} on error.

@subheading Example

@example
FILE *stdprn = fdopen(4, "w");
@end example

@c ----------------------------------------------------------------------
@node feof, ferror, fdopen, Alphabetical List

@heading @code{feof}
@subheading Syntax

@example
#include <stdio.h>

int feof(FILE *file);
@end example

@subheading Description

This function (actually a macro) can be used to indicate if the given
@var{file} is at the end-of-file or not.

@subheading Return Value

Nonzero at end-of-file, zero otherwise.

@subheading Example

@example
while (!feof(stdin))
  gets(line);
@end example

@c ----------------------------------------------------------------------
@node ferror, fflush, feof, Alphabetical List

@heading @code{ferror}
@subheading Syntax

@example
#include <stdio.h>

int ferror(FILE *file);
@end example

@subheading Description

This function (actually a macro) can be used to indicate if the given
@var{file} has encountered an error or not.  @xref{clearerr}

@subheading Return Value

Nonzero for an error, zero otherwize.

@subheading Example

@example
if (ferror(stdin))
  exit(1);
@end example

@c ----------------------------------------------------------------------
@node fflush, ffs, ferror, Alphabetical List

@heading @code{fflush}
@subheading Syntax

@example
#include <stdio.h>

int fflush(FILE *file);
@end example

@subheading Description

This function causes any unwritten buffered data to be written out to
the given @var{file}.  This is useful in cases where the output is line
buffered and you want to write a partial line.

@subheading Return Value

Zero on success, -1 on error.

@subheading Example

@example
printf("Enter value : ");
fflush(stdout);
scanf(result);
@end example

@c ----------------------------------------------------------------------
@node ffs, fgetc, fflush, Alphabetical List

@heading @code{ffs}
@subheading Syntax

@example
#include <string.h>
int ffs(int mask);
@end example

@subheading Description

This function returns the position of the least significant bit set in
@var{mask}.  For example:

@example
ffs(0x00000000) == 0
ffs(0x00000001) == 1
ffs(0x00000002) == 2
ffs(0x00000004) == 3
ffs(0x00010000) == 17
ffs(0x00010010) == 5
@end example

@subheading Return Value

The position of the bit, or zero if none are set.

@c ----------------------------------------------------------------------
@node fgetc, fgetgrent, ffs, Alphabetical List

@heading @code{fgetc}
@subheading Syntax

@example
#include <stdio.h>

int fgetc(FILE *file);
@end example

@subheading Description

Returns the next character in the given @var{file} as an unsigned char.

@subheading Return Value

The given char (value 0..255) or @code{EOF} at end-of-file.

@subheading Example

@example
int c;
while((c=fgetc(stdin)) != EOF)
  fputc(c, stdout);
@end example

@c ----------------------------------------------------------------------
@node fgetgrent, fgetpos, fgetc, Alphabetical List

@heading @code{fgetgrent}
@subheading Syntax

@example
#include <grp.h>

struct group *fgetgrent(FILE *file);
@end example

@subheading Description

This function, in MS-DOS, is exactly the same as getgrent
(@xref{getgrent}).

@c ----------------------------------------------------------------------
@node fgetpos, fgetpwent, fgetgrent, Alphabetical List

@heading @code{fgetpos}
@subheading Syntax

@example
#include <stdio.h>

int fgetpos(FILE *file, fpos_t *offset);
@end example

@subheading Description

This function records the current file pointer for @var{file}, for
later use by @code{fsetpos}.

@xref{fsetpos}.

@xref{ftell}.

@subheading Return Value

Zero if successful, nonzero if not.

@c ----------------------------------------------------------------------
@node fgetpwent, fgets, fgetpos, Alphabetical List

@heading @code{fgetpwent}
@subheading Syntax

@example
#include <pwd.h>

struct passwd *fgetpwent(FILE *file);
@end example

@subheading Description

This function, in MS-DOS, is exactly like @code{getpwent}
(@xref{getpwent}).

@c ----------------------------------------------------------------------
@node fgets, _filbuf, fgetpwent, Alphabetical List

@heading @code{fgets}
@subheading Syntax

@example
#include <stdio.h>

char *fgets(char *buffer, int maxlength, FILE *file);
@end example

@subheading Description

This function reads as much of a line from a file as possible, stopping
when the buffer is full (@var{maxlength}-1 characters), an end-of-line
is detected, or @code{EOF} or an error is detected.  It then stores a
@code{NULL} to terminate the string.

@subheading Return Value

The address of the buffer is returned on success, if @code{EOF} is
encountered before any characters are stored, or if an error is
detected, @code{NULL} is returned instead.

@subheading Example

@example
char buf[100];
while (fgets(buf, 100, stdin))
  fputs(buf, stdout);
@end example

@c ----------------------------------------------------------------------
@node _filbuf, fileno, fgets, Alphabetical List

@heading @code{_filbuf}

@subheading Description

This is an internal function used to implement stream buffering.

@c ----------------------------------------------------------------------
@node fileno, _findenv, _filbuf, Alphabetical List

@heading @code{fileno}
@subheading Syntax

@example
#include <stdio.h>

int fileno(FILE *file);
@end example

@subheading Description

This function returns the raw file descriptor number that @var{file}
uses for I/O.

@subheading Return Value

The file descriptor number.

@c ----------------------------------------------------------------------
@node _findenv, findfirst, fileno, Alphabetical List

@heading @code{_findenv}

@subheading Description

This is an internal function used by @code{getenv} and @code{setenv}.
@xref{getenv} @xref{setenv}

@c ----------------------------------------------------------------------
@node findfirst, _findiop, _findenv, Alphabetical List

@heading @code{findfirst}
@subheading Syntax

@example
#include <dir.h>

int findfirst(const char *pathname, struct ffblk *ffblk, int attrib);
@end example

@subheading Description

This function and the related @code{findnext} are used to scan
directories for the list of files therein.  The @var{pathname} is a
wildcard that specifies the directory and files to search for (such as
@code{subdir/*.c}), @var{ffblk} is a structure to hold the results and
state of the search, and @var{attrib} is a combination of the following:

@table @code

@item FA_RDONLY

Include read-only files in the search

@item FA_HIDDEN

Include hidden files in the search

@item FA_SYSTEM

Include system files in the search

@item FA_LABEL

Include the volume label in the search

@item FA_DIREC

Include subdirectories in the search

@item FA_ARCH

Include modified files in the search

@end table

Any file that doesn't have any flag bits that aren't specified is
selected for the search.  Thus, if you specified @code{FA_DIREC} and
@code{FA_LABEL}, you would get all subdirectories, the volume label, and
any file that is neither read-only or modified.

The results of the search are stored in @var{ffblk}:

@example
struct ffblk @{
  char ff_reserved[21];  /* used to hold the state of the search */
  char ff_attrib;        /* actual attributes of the file found */
  short ff_ftime;        /* hours:5, minutes:6, (seconds/2):5 */
  short ff_fdate;        /* (year-1980):7, month:4, day:5 */
  short ff_filler;       /* gcc aligns "long" different than DOS */
  long ff_fsize;         /* size of file */
  char ff_name[16];      /* name of file as ASCIIZ string */
@}
@end example

@subheading Return Value

Zero if a match is found, nonzero if none found.

@subheading Example

@example
struct ffblk f;
int done = findfirst("*.exe", &f, FA_ARCH|FA_RDONLY);
while (!done)
@{
  printf("%10u %2d:%02d:%02d %2d/%02d/%4d %s\n",
    f.ff_fsize,
    (f.ff_ftime >> 11) & 0x1f,
    (f.ff_ftime >>  5) & 0x3f,
    (f.ff_ftime & 0x1f) * 2,
    (f.ff_fdate >>  5) & 0x0f,
    (f.ff_fdate & 0x1f),
    ((f.ff_fdate >> 9) & 0x7f) + 1980,
    f.ff_name);
  done = findnext(&f);
@}
@end example

@c ----------------------------------------------------------------------
@node _findiop, findnext, findfirst, Alphabetical List

@heading @code{_findiop}

@subheading Description

This is an internal function used by @code{fopen}. @xref{fopen}

@c ----------------------------------------------------------------------
@node findnext, _fixpath, _findiop, Alphabetical List

@heading @code{findnext}
@subheading Syntax

@example
#include <dir.h>

int findnext(struct ffblk *ffblk);
@end example

@subheading Description

This finds the next file in the search started by @code{findfirst}. @xref{findfirst}

@subheading Return Value

Zero if there was a match, else nonzero.

@c ----------------------------------------------------------------------
@node _fixpath, _flsbuf, findnext, Alphabetical List

@heading @code{_fixpath}
@subheading Syntax

@example
void _fixpath(const char *in_path, char *out_path);
@end example

@subheading Description

This function canonacalizes the input path @var{in_path} and stores the
result in the buffer pointed to by @var{out_path}.

The path is fixed by removing consecutive and trailing slashes, making
the path absolute if it's relative, removing "." components, collapsing
".." components, adding a drive specifier if needed, and converting all
slashes to '/'.

@subheading Return Value

None.

@subheading Example

@example
char oldpath[100], newpath[100];
scanf(oldpath);
_fixpath(oldpath, newpath);
printf("that really is %s\n", newpath);
@end example

@c ----------------------------------------------------------------------
@node _flsbuf, _fmode, _fixpath, Alphabetical List

@heading @code{_flsbuf}

@subheading Description

This is an internal function used to implement stream buffering.

@c ----------------------------------------------------------------------
@node _fmode, fnmatch, _flsbuf, Alphabetical List

@heading @code{_fmode}
@subheading Syntax

@example
#include <fcntl.h>

extern int _fmode;
@end example

@subheading Description

This variable may be set to @code{O_TEXT} or @code{O_BINARY} to specify
the mode that newly opened files should be opened in if the open call
did not specify.  @xref{open} @xref{fopen}

The default value is @code{O_TEXT}.

@subheading Example

@example
_fmode = O_BINARY;
@end example

@c ----------------------------------------------------------------------
@node fnmatch, fnmerge, _fmode, Alphabetical List

@heading @code{fnmatch}
@subheading Syntax

@example
#include <unistd.h>

int fnmatch(const char *pattern, const char *string, int flags);
@end example

@subheading Description

This function indicates if @var{string} matches the @var{pattern}.  The
pattern may include the following special characters:

@table @code

@item *

Matches zero of more characters.

@item ?

Matches exactly one character

@item [...]

Matches one character if it's in a range of characters.  If the first
character is @code{!}, matches if the character is not in the range.
Between the brackets, the range is specified by listing the characters
that are in the range, or two characters separated by @code{-} to
indicate all characters in that range.  For example, @code{[a-d]}
matches @code{a}, @code{b}, @code{c}, or @code{d}.

@item \

Causes the next character to not be treated as a wildcard.  For example,
@code{\*} matches an asterisk.  This is only available if @var{flags}
includes @code{FNM_QUOTE}.

@end table

The value of @var{flags} is a combination of zero of more of the
following:

@table @code

@item FNM_PATHNAME

This means that the string should be treated as a pathname, in that the
slash character @code{/} never matches any of the wildcards.

@item FNM_QUOTE

This means that the backslash @code{\\} may be used for quoting special
characters in the pattern.

@end table

@subheading Return Value

Zero if the string does not match, nonzero if it does.

@subheading Example

@example
if (fnmatch("*.[ch]", filename, FNM_PATH|FNM_QUOTE))
  do_source_file(filename);
@end example

@c ----------------------------------------------------------------------
@node fnmerge, fnsplit, fnmatch, Alphabetical List

@heading @code{fnmerge}
@subheading Syntax

@example
#include <dir.h>

void fnmerge (char *path, const char *drive, const char *dir,
        const char *name, const char *ext);
@end example

@subheading Description

This function constructs a file @var{path} from its components.

@xref{fnsplit}

@subheading Return Value

None.

@subheading Example

@example
char buf[MAXPATH];
fnmerge(buf, "d:", "/foo/", "data", ".txt");
@end example

@c ----------------------------------------------------------------------
@node fnsplit, fopen, fnmerge, Alphabetical List

@heading @code{fnsplit}
@subheading Syntax

@example
#include <dir.h>

int fnsplit (const char *path, char *drive, char *dir,
        char *name, char *ext);
@end example

@subheading Description

This function decomposes a @var{path} into its components.

@xref{fnmerge}

@subheading Return Value

A flag that indicates which components were found:

@table @code

@item DRIVE

The drive letter was found.

@item DIRECTORY

A directory or subdirectories was found.

@item FILENAME

A filename was found.

@item EXTENSION

An extension was found.

@item WILDCARDS

The path included @code{*} or @code{?}.

@end table

@subheading Example

@example
char d[MAXDRIVE], p[MAXDIR], f[MAXFILE], e[MAXEXT];
int which = fnsplit("d:/djgpp/bin/gcc.exe", d, p, f, e);
d = "d:"
p = "/djgpp/bin/"
f = "gcc"
e = ".exe"
@end example

@c ----------------------------------------------------------------------
@node fopen, fork, fnsplit, Alphabetical List

@heading @code{fopen}
@subheading Syntax

@example
#include <stdio.h>
FILE *fopen(const char *filename, const char *mode);
@end example

@subheading Description

This function opens a stream corresponding to the named @var{filename}
with the given @var{mode}.  The mode can be one of the following:

@table @code

@item r

Open an existing file for reading.

@item w

Create a new file (or truncate an existing file) and open it for
writing.

@item a

Open an existing file (or create a new one) for writing.  The file
pointer is positioned to the end of the file before every write.

@end table

Followed by any of these characters:

@table @code

@item b

Force the file to be open in binary mode instead of the default mode.

@item t

Force the file to be open in text mode instead of the default mode.

@item +

Open the file as with @code{O_RDWR} so that both reads and writes
can be done to the same file.

@end table

If the file is open for both reading and writing, you must call
@code{fflush}, @code{fseek}, or @code{rewind} before switching from read
to write or from write to read.

The open file is set to line buffered if the underlying object is a
device (stdin, stdout, etc), or is fully buffered if the underlying
object is a disk file (data.c, etc).

If @code{b} or @code{t} is not specified in @var{mode}, the file type is
chosen by the value of @code{fmode} (@xref{_fmode}).

@subheading Return Value

A pointer to the @code{FILE} object, or @code{NULL} if there was an
error.

@subheading Example

@example
FILE *f = fopen("foo", "rb+"); /* open existing file for read/write, binary mode */
@end example

@c ----------------------------------------------------------------------
@node fork, fpathconf, fopen, Alphabetical List

@heading @code{fork}

@subheading Description

This function always returns -1, as MS-DOS does not support multiple
processes.  It exists only to assist in porting Unix programs.

@c ----------------------------------------------------------------------
@node fpathconf, fprintf, fork, Alphabetical List

@heading @code{fpathconf}
@subheading Syntax

@example
#include <unistd.h>

long fpathconf(int fd, int name);
@end example

@subheading Description

Returns configuration information on the filesystem that the
open file resides on.  @xref{pathconf}

@subheading Return Value

The configuration value.

@c ----------------------------------------------------------------------
@node fprintf, fpurge, fpathconf, Alphabetical List

@heading @code{fprintf}
@subheading Syntax

@example
#include <stdio.h>

int fprintf(FILE *file, const char *format, @dots{});
@end example

@subheading Description

Prints formatted output to the named file.  @xref{printf}

@subheading Return Value

The number of characters written.

@c ----------------------------------------------------------------------
@node fpurge, fputc, fprintf, Alphabetical List

@heading @code{fpurge}
@subheading Syntax

@example
#include <stdio.h>

int fpurge(FILE *file);
@end example

@subheading Description

This function purges the buffer for @var{file} without writing it to
disk.

@subheading Return Value

Zero on success, -1 on failure.

@c ----------------------------------------------------------------------
@node fputc, fputs, fpurge, Alphabetical List

@heading @code{fputc}
@subheading Syntax

@example
#include <stdio.h>

int fputc(int character, FILE *file);
@end example

@subheading Description

This function writes the given @var{character} to the given @code{file}.

@subheading Return Value

The given character [0..255] or @code{EOF}.

@subheading Example

@example
fputc('\n', stdout);
@end example

@c ----------------------------------------------------------------------
@node fputs, fread, fputc, Alphabetical List

@heading @code{fputs}
@subheading Syntax

@example
#include <stdio.h>

int fputs(const char *string, FILE *file);
@end example

@subheading Description

This function all the characters of @var{string} (except the trailing
@code{NULL}) to the given @var{file}.

@subheading Return Value

A nonnegative number on success, @code{EOF} on error.

@subheading Example

@example
fputs("Hello\n", stdout);
@end example

@c ----------------------------------------------------------------------
@node fread, free, fputs, Alphabetical List

@heading @code{fread}
@subheading Syntax

@example
#include <stdio.h>

size_t fread(void *buffer, size_t size, size_t number, FILE *file);
@end example

@subheading Description

This function reads @var{size}*@var{number} characters from @var{file}
to @var{buffer}.

@subheading Return Value

The number of items of size @var{size} read, or -1 on error.

@subheading Example

@example
int foo[10];
fread(foo, sizeof(int), 10, stdin);
@end example

@c ----------------------------------------------------------------------
@node free, freopen, fread, Alphabetical List

@heading @code{free}
@subheading Syntax

@example
#include <stdio.h>

void free(void *ptr);
@end example

@subheading Description

Returns the allocated memory to the heap (@xref{malloc}).  If the
@var{ptr} is @code{NULL}, it does nothing.

@subheading Return Value

None.

@subheading Example

@example
char *q = (char *)malloc(20);
free(q);
@end example

@c ----------------------------------------------------------------------
@node freopen, fscanf, free, Alphabetical List

@heading @code{freopen}
@subheading Syntax

@example
#include <stdio.h>

FILE *freopen(const char *filename, const char *mode, FILE *file);
@end example

@subheading Description

This function closes @var{file} if it was open, then opens a new
file like @code{fopen(filename, mode)} but it reuses @var{file}.

This is useful to, for example, associate @code{stdout} with a new file.

@subheading Return Value

The new file, or @code{NULL} on error.

@subheading Example

@example
freopen("/tmp/stdout.dat", "wb", stdout);
@end example

@c ----------------------------------------------------------------------
@node fscanf, fseek, freopen, Alphabetical List

@heading @code{fscanf}
@subheading Syntax

@example
#include <stdio.h>

int fscanf(FILE *file, const char *format, @dots{});
@end example

@subheading Description

This function scans formatted text from @var{file} and stores it in the
variables pointed to by the arguments.  @xref{scanf}

@subheading Return Value

The number of items successfully scanned.

@c ----------------------------------------------------------------------
@node fseek, fsetpos, fscanf, Alphabetical List

@heading @code{fseek}
@subheading Syntax

@example
#include <stdio.h>

int fseek(FILE *file, long offset, int mode);
@end example

@subheading Description

This function moves the file pointer for @var{file} according to
@var{mode}:

@table @code

@item SEEK_SET

The file pointer is moved to the offset specified.

@item SEEK_CUR

The file pointer is moved relative to its current position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The offset is usually nonpositive in this case.

@end table

@emph{Warning!} The ANSI standard only allows values of zero for
@var{offset} when @var{whence} is not @code{SEEK_SET} and the file has
been opened as a text file.  Although this restriction is not enforced,
beware that there is not a one-to-one correspondence between file
characters and text characters under MS-DOS, so some @code{fseek}
operations may not do exactly what you expect.

@subheading Return Value

Zero if successful, nonzero if not.

@subheading Example

@example
fseek(stdin, 12, SEEK_CUR); /* skip 12 bytes */
@end example

@c ----------------------------------------------------------------------
@node fsetpos, fstat, fseek, Alphabetical List

@heading @code{fsetpos}
@subheading Syntax

@example
#include <stdio.h>

int fsetpos(FILE *file, const fpos_t *offset);
@end example

@subheading Description

This function moves the file pointer for @var{file} to position
@var{offset}, as recorded by @code{fgetpos}.

@xref{fgetpos}.

@xref{fseek}.

@subheading Return Value

Zero if successful, nonzero if not.

@c ----------------------------------------------------------------------
@node fstat, fsync, fsetpos, Alphabetical List

@heading @code{fstat}
@subheading Syntax

@example
#include <sys/stat.h>

int fstat(int file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the open file @var{file} and stores
it in @var{sbuf}.  @xref{stat}

@subheading Return Value

Zero on success, nonzero on failure.

@c ----------------------------------------------------------------------
@node fsync, ftell, fstat, Alphabetical List

@heading @code{fsync}
@subheading Syntax

@example
#include <osfcn.h>

int fsync(int file);
@end example

@subheading Description

Forces all information about the file to be synchronized with the disk
image.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
fsync(fileno(stdout));
@end example

@c ----------------------------------------------------------------------
@node ftell, ftime, fsync, Alphabetical List

@heading @code{ftell}
@subheading Syntax

@example
#include <stdio.h>

long ftell(FILE *file);
@end example

@subheading Description

Returns the current file position for @code{file}.  This is suitable for
a future call to @code{fseek}.

@subheading Return Value

The file position, or -1 on error.

@subheading Example

@example
long p = ftell(stdout);
@end example

@c ----------------------------------------------------------------------
@node ftime, ftruncate, ftell, Alphabetical List

@heading @code{ftime}
@subheading Syntax

@example
#include <sys/timeb.h>

int ftime(struct timeb *buf);
@end example

@subheading Description

This function stores the current time in the structure @var{buf}.  The
format of @code{struct timeb} is:

@example
struct timeb @{
  time_t         time;     /* seconds since 00:00:00 GMT 1/1/1970 */
  unsigned short millitm;  /* milliseconds */
  short          timezone; /* difference between GMT and local, minutes */
  short          dstflag;  /* set if daylight savings time in affect */
@};
@end example

@subheading Return Value

Zero on success, nonzero on error.

@subheading Example

@example
struct timeb t;
ftime(&t);
@end example

@c ----------------------------------------------------------------------
@node ftruncate, _fwalk, ftime, Alphabetical List

@heading @code{ftruncate}
@subheading Syntax

@example
#include <osfcn.h>

int ftruncate(int file, unsigned long where);
@end example

@subheading Description

This function truncates @var{file} at @var{where} length.  This only
works if the file is closed right after this call.

@subheading Return Value

Zero for success, nonzero for failure.

@subheading Example

@example
int x = open("data", O_WRONLY);
ftruncate(x, 1000);
close(x);
@end example

@c ----------------------------------------------------------------------
@node _fwalk, fwrite, ftruncate, Alphabetical List

@heading @code{_fwalk}
@subheading Syntax

@example
void _fwalk(void (*function)(FILE *file));
@end example

@subheading Description

For each open file in the system, the given @var{function} is called,
passing the file pointer as it's only argument

@subheading Return Value

None.

@subheading Example

@example
void pfile(FILE *x)
@{ printf("FILE at %x\n", x); @}

_fwalk(pfile);
@end example

@c ----------------------------------------------------------------------
@node fwrite, _get_default_drive, _fwalk, Alphabetical List

@heading @code{fwrite}
@subheading Syntax

@example
#include <stdio.h>

size_t fwrite(void *buffer, size_t size, size_t number, FILE *file);
@end example

@subheading Description

This function writes @var{size}*@var{number} characters from @var{buffer}
to @var{file}.

@subheading Return Value

The number of items of size @var{size} written, or -1 on error.

@subheading Example

@example
int foo[10];
fwrite(foo, sizeof(int), 10, stdin);
@end example